
package data;

import java.sql.Connection;
import java.util.List;
import java.util.Map;

import data.bean.DataBean;
import data.bean.DatabaseField;
import data.exception.DaoException;

/**
 * The DAO Interface for database access (corresponding to a DataBean). 
 * It is database independent.
 * 
 * @author chuxiaoyuan
 */
public interface IDao<Bean extends DataBean> {

	/**
	 * Get new connection 
	 */
	Connection getConnection() throws DaoException;

	/**
	 * Close connection
	 */
	void closeConnection() throws DaoException;
	
	/**
	 * Set connection.
	 * @param connection the connection instance.
	 */
	void setConnection(Connection connection) throws DaoException;
	
	/**
	 * Indicates if this DAO is inside big transactions.
	 * 
	 * @return true if it is inside transactions.
	 */
	boolean isTransactional();
	
	/**
	 * Set if this DAO is inside big transactions.
	 * 
	 * @param transactional true if it is inside transactions.
	 */
	void setTransactional(boolean transactional);
	
	/**
	 * Get table name.
	 * 
	 * @return get the table name.
	 */
	String getTableName();
	
	/**
	 * Get all the fields.
	 * 
	 * @return the data fields.
	 */
	List<DatabaseField> getFields();

	/**
	 * Get the fields of the specified names.
	 * 
	 * @return the data fields.
	 */
	List<DatabaseField> getFields(List<String> fieldsName);
	
	/**
	 * Get the specified field.
	 * 
	 * @param fieldName the field name.
	 * @return the field.
	 */
	DatabaseField getField(String fieldName);
	
	/**
	 * Test if this is corresponding to a table entity.
	 * 
	 * @return true if it is a table.
	 */
	boolean isTableEntity();
	
	/**
	 * Insert new object.
	 * !Note: Auto generated fields will  be populated in the bean but the 
	 * JDBC API is not well supported by every database vender.
	 * 
	 * @param bean
	 *            a data bean object contains the to-be-insert data.
	 *            Auto generated fields will be ignored.
	 * @return inserted row count
	 */
	int insert(Bean bean) throws DaoException;
	
	/**
	 * Delete by primary key.
	 * 
	 * @param bean
	 *            a data bean object contains the primary key to be deleted.
	 * @return deleted row count
	 */
	int delete(Bean bean) throws DaoException;

	/**
	 * Delete all.
	 * 
	 * @return deleted row count
	 */
	int deleteAll() throws DaoException;
	
	/**
	 * Update by primary key.
	 * 
	 * @param bean
	 *            a data bean object.
	 * @return insert row count
	 */
	int update(Bean bean) throws DaoException;

	/**
	 * Select by one field value and pagination requirement.
	 */
	List<Bean> selectByField(String fieldName, Object value, Pagination pagination) throws DaoException;
	
	/**
	 * Select by one field value.
	 */
	List<Bean> selectByField(String fieldName, Object value) throws DaoException;

	/**
	 * Select by the primary key.
	 * 
	 * @return the matched bean (should be unique). or null if not found.
	 */
	Bean selectByPrimaryKey(Map<String, Object> pk) throws DaoException;

	/**
	 * Select all with pagination.
	 */
	List<Bean> selectAll(Pagination pagination) throws DaoException;
	
	/**
	 * Select all.
	 */
	List<Bean> selectAll() throws DaoException;
}
